<HDML>

An HDML deck is used to transport and cache sets of HDML cards. It is the smallest unit of HDML a service can transmit to the UP.Link server, and the only HDML unit for which you can specify a Time To Live (TTL)--the period during which the phone caches the deck.

You can also use a deck to group cards for which you want to set the same bookmarking and access settings.

To define a deck, you use an <HDML> statement. The statement must include one or more statements defining display, choice, or entry cards. It can also specify options and actions that apply to the entire deck.

Syntax

 
<HDML Beginning of the deck header. 
  VERSION=version_num The version of the HDML language used for the deck. The syntax is maj.min.lex, where maj is the major version, min is the minor version, and lex is the lexical version. The lexical version number is optional. Valid version numbers are 0.1 and 3.0.

You must specify a version number. If you do not, the HDML compiler generates an error message. 
  TTL=cache_time The number of seconds the UP.Phone should cache the deck after it receives it. 

If you do not specify a value, the UP.Phone caches the deck for 30 days. If cache_time is 0, the UP.Phone does not cache the deck at all. 
  MARKABLE=boolean Flag specifying whether the cards in the deck can be marked. To allow the cards to be marked, specify TRUE. The default value is FALSE. 

If you set the MARKABLE option to TRUE, it implicitly sets the PUBLIC option to TRUE, allowing other URLs to link directly to cards within the deck. 

If the statement for a card within the deck specifies the MARKABLE option, it overrides the deck's MARKABLE option. 
  PUBLIC=boolean Specifies whether deck access control is enabled. If you specify TRUE, any deck can link to cards within the deck. If you specify FALSE, only decks that have domains and paths specified by the ACCESSDOMAIN and ACCESSPATH options can link to cards within the deck. 

The default is FALSE. 
  ACCESSDOMAIN=domain Specifies the domain of URLs that are allowed to request cards in the deck if PUBLIC is set to FALSE. 

The default value is the current deck's domain. 
 
 
  ACCESSPATH=path Specifies the base path of URLs that are allowed to request cards within the deck when PUBLIC is set to FALSE. 

The default value is / (the root of the current deck's path); this means that any deck with the domain specified by ACESSDOMAIN can request the deck. 
 
 
> End of the deck header. 
actions  Actions that apply to the entire deck. 
cards  One or more cards. A deck must contain at least one card. 
</HDML> The deck footer. 
IMPORTANT    The UP.Link server cannot transmit compiled HDML decks or digests larger then 1492 bytes to UP.Phones. If you send a deck larger than 1492 bytes to the UP.Link server, the UP.Link server generates an error. Because compiling a deck can increase or decrease its size slightly, uncompiled decks slightly smaller than 1492 bytes may also fail. To be safe, you should attempt to keep all uncompiled decks smaller than 1200 bytes.

Examples

The following HDML statements generate the display shown in Figure 2-10: FIGURE  2-10.    Deck with a single display card

Suppose you want to make sure the UP.Phone does not cache the card. You also want to allow the user to mark the deck. To do this, you change the HDML statements to the following:

When you specify the MARKABLE=TRUE option, the mark (MARK) label appears as shown in Figure 2-11. Note that some phones do not display the mark label.

FIGURE  2-11.    Display card with the MARKABLE=TRUE option